Extension: .d00
Version: 4.00 (Player Version)
Created by: Jens-Christian Huus (JCH/Vibrants)
Tracker: Edlib Tracker
Players: Edlib, ...
Description by: JCH/Vibrants
Taken from: Edlib v1.05a rev 055
Note: Adlib (OPL2) music format
┌─────────────────────────────────────────────────────────────────────────────┐
│ How to use Player v04.00 ............................ by Jens-Christian Huus│
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ │
│ INTRODUCTION │
│ ──────────── │
│ │
│ So you have finally managed to fumble you way around the editor │
│ and now you want to use the music in your demo or other piece of │
│ programming not earning you any money (Because THAT's the deal)! │
│ All right, in this directory you will find the OBJ player needed │
│ to link onto your own program. This DOC will tell you about the │
│ functions and variables in the player plus the file formats. │
│ │
│ After having done your tune in the editor - saving the source to │
│ disk with Shift-F12 or Ctrl-F4 - you must convert it to a format │
│ with the ".D00" extension. Do this by pressing Ctrl-F5 while in │
│ the editor. The music will be packed to a fully playable format │
│ which takes up little memory (typically 2-5 Kb). Now you can use │
│ this file together with "MPLAYER.OBJ" in this directory. │
│ │
│ NOTE: You cannot load ".D00" files into EdLib. Make sure you DID │
│ save that masterpiece with Shift-F12 or Ctrl-F4 before packing! │
│ │
│ │
│ THE TEST PROGRAM │
│ ──────────────── │
│ │
│ Before describing the functions in the player, have a look at my │
│ example file "TEST.ASM" to see how I use the "STR_WISE.D00" file │
│ by Drax. The source was assembled using Turbo Assembler v4.0 and │
│ linked using Turbo Link v6.00, both from Borland. You can use my │
│ makefile "-" to accomplish this, but check it out first - I have │
│ used the 4DOS command "keystack 13" to skip the annoying "Press │
│ any key to continue" message before reentering my source editor. │
│ I have also used a "mode co80,50" to switch into 50 lines mode, │
│ a mode I use a lot when programming. │
│ │
│ The file "GLOBALS.INC" is included in the source. This file con- │
│ tains most of the variables in the player, but in the TEST file │
│ I only use the "GLOBAL PLAYER:FAR" line to call the player. Some │
│ of the other variables will be discussed later, as they can be │
│ used to make scopes or the like in your own programs. │
│ │
│ The execution of the "TEST.ASM" file is simple - first it checks │
│ if an OPL2 chip is present using a function in the player. If it │
│ isn't, an error is printed and the program is aborted. Otherwise │
│ the ".D00" is loaded, the player initialized and started. I have │
│ used a standard timer interrupt routine to call the AdLib player │
│ as many times as it was used in the editor (this information is │
│ saved into the ".D00" file). The source code has been commented │
│ all the way, so I guess I don't have to say more than that. │
│ │
│ │
│ PLAYER FUNCTIONS │
│ ──────────────── │
│ │
│ Use the "CALL PLAYER" label prepared by "GLOBAL PLAYER:FAR" with │
│ registers prepared to access all player functions. The player is │
│ from my old school, so no registers are pushed I'm afraid. Do it │
│ yourself. Here is a list of the functions currently available in │
│ this version of the player. │
│ │
│ │
│ MAIN RESET AH 00h │
│ BX:CX Segment:offset of ".D00" data #1 │
│ ES:DI Segment:offset of ".D00" data #2 │
│ │
│ Initializes the soundcard, clears variables and resets constants │
│ as well as informing the player of the location of the tune. The │
│ ES:DI pair is normally not of any interest to you. It was used │
│ in games such as "Lollypop" to split up musics and SFX into two │
│ parts; one for general stuff and one for level-specific stuff. │
│ │
│ │
│ RESET AH 01h │
│ │
│ Use this function whenever you want to stop the player. Eg, when │
│ quitting to DOS and stuff like that. Clears all variables too. │
│ │
│ │
│ START AH 02h │
│ BX Tune number (Usually 0000h) │
│ │
│ Actually starts the tune. In BX more than one piece of music can │
│ be triggered, something that was useful in games. However, EdLib │
│ does not know how to pack more than one tune at this moment - so │
│ I guess you have to tap a 0000h there, no matter what. │
│ │
│ │
│ PLAY AH 03h │
│ │
│ This is the function that goes into the timer interrupt or maybe │
│ the vertical retrace. Whatever. Just as long as you update it as │
│ many times as the 8th byte in the ".D00" file is set to. EdLib │
│ sets this byte to 70 (46h) as default. │
│ │
│ │
│ TOGGLE AH 04h │
│ BX Tune number (Usually 0000h) │
│ │
│ Pauses the music instantly. This feature is very useful in games │
│ when the pause button is pressed. Calling it once more continues │
│ the music to the best of its abilities; notes falling in quickly │
│ makes the continuation faultless. But if the notes were long... │
│ │
│ │
│ MAINVOL AH 05h │
│ BL Main volume for part one │
│ BH Main volume for part two │
│ CL Dividing line │
│ │
│ This main volume is a little more complicated than a normal main │
│ volume routine. Using values of 00h-3Fh in BL or/and BH you can │
│ split the main volume up into certain voice parts. Knowing that │
│ AdLib has 9 voices, a value of 04h in CL splits up the two reg's │
│ into voices 0-3 and 4-8. In games such as "Lollypop" this was │
│ very useful when seperating main volumes for music or SFX, since │
│ the SFX used voices 0-3 and the music voices 4-8. NOTE: AdLib is │
│ upside down concerning level (volume) values; use 3Fh as silent. │
│ │
│ │
│ SCAN AH 06h │
│ │
│ CF=0 If the card was detected │
│ │
│ Tries to detect the OPL2 chip (standard AdLib FM chip) using the │
│ AdLib timer method. If it fails, the carry is set. NOTE: In some │
│ occasions the detection will fail if there is both a GUS (Gravis │
│ Ultrasound) and an OPL2 based soundcard in the computer at once. │
│ It is recommended that you make it possible to override it. Make │
│ a switch on the commandline or something like that. │
│ │
│ │
│ BREAK/CONTINUE AH 07h │
│ BL=0 Break, otherwise (if BL<>0) continue │
│ │
│ This is not a function I can imagine you're ever going to use. I │
│ made it to make it possible to break the tune, "remember" where │
│ it came and start another tune (going into a sublevel). When the │
│ sublevel was over, this function would then continue on the song │
│ it "remembered". Since EdLib does not allow more than one piece │
│ of music in a ".D00" file, it is not of much use to you! :( │
│ │
│ │
│ REQUEST AH 08h │
│ BX Tune number (Usually 0000h) │
│ │
│ CF=1 If it is still running │
│ │
│ Simply checks if a tune or SFX ends. Needless to say it requires │
│ that you use the "FFFExxxx" endmarks in all of the tracks! It is │
│ not of much use to you, but in games it was worth every penny. │
│ │
│ │
│ PLAYER HEADER VARIABLES │
│ ─────────────────────── │
│ │
│ From offset 0000h in the player I have put certain constants and │
│ variables at places that will stay the same in every player that │
│ may be developed for EdLib. These may come in handy if creating │
│ some sort of ".D00" shell which loads the player. │
│ │
│ │
│ Offset Description │
│ ────── ─────────── │
│ │
│ 0000h-0002h JMP to all functions which ends with RETF │
│ │
│ 0003h-0008h Detection bytes ('JCH',26h,02h,66h) │
│ │
│ 0009h-000ah Current card player version (0400h) │
│ │
│ 000bh Indicates normal OPL2 player (00h) │
│ │
│ 000ch Number of voices supported (09h) │
│ │
│ 000dh-002ch 32 bytes card name ('AdLib ') │
│ │
│ 002dh-002eh Pointer to "Inst" variables │
│ │
│ 002fh Indicates that "Inst" is WORD-based (01h) │
│ │
│ 0030h-0031h Pointer to "Dur" variables │
│ │
│ 0032h Indicates that "Dur" is WORD-based (01h) │
│ │
│ 0033h-0034h Pointer to "SeqPoi" variables │
│ │
│ 0035h Indicates that "SeqPoi" is WORD-based (01h) │
│ │
│ 0036h-0037h Pointer to "TrackPoi" variables │
│ │
│ 0038h Indicates that "TrackPoi" is WORD-based (01h) │
│ │
│ 0039h-003ah Pointer to "Freq" variables │
│ │
│ 003bh Indicates that "Freq" is WORD-based (01h) │
│ │
│ 003ch-003dh Pointer to "Spedr" variables │
│ │
│ 003eh Indicates that "Spedr" is BYTE-based (00h) │
│ │
│ 003fh-0040h Pointer to "Gate" variables │
│ │
│ 0041h Indicates that "Gate" is BYTE-based (00h) │
│ │
│ 0042h-0043h Pointer to "Nog" variables │
│ │
│ 0044h Indicates that "Nog" is BYTE-based (00h) │
│ │
│ 0045h-0046h Pointer to "Note" variables │
│ │
│ 0047h Indicates that "Note" is BYTE-based (00h) │
│ │
│ 0048h-0067h 32 bytes reserved for future expansion │
│ │
│ 0068h-0070h ON/OFF flags for all 9 voices (00h=Off) │
│ │
│ 0071h-????h Copyright string, and rest of player │
│ │
│ │
│ Some notes about the information above may be necessary. │
│ │
│ The JMP at position 0000h makes it possible to turn the player │
│ into a BIN-file and just call the player from offset 0000h. │
│ │
│ You may wonder about the detection bytes. The 'JCH' is of course │
│ my initials. 26h,02h,66h is my birthdate; 26th of february 1966. │
│ │
│ Offset 000bh-002ch was made to identify this player from players │
│ written for other soundcards. I soon burried this idea. │
│ │
│ All the variables pointers each points to nine bytes or words in │
│ which you may find valuable information for shell programs. Here │
│ is a deeper explanation of these variables... │
│ │
│ │
│ "Inst" 9 WORDS Current instrument played │
│ │
│ "Dur" 9 WORDS Realtime note duration counters │
│ │
│ "SeqPoi" 9 WORDS Realtime sequence position │
│ │
│ "TrackPoi" 9 WORDS Realtime track position │
│ │
│ "Freq" 9 WORDS Actual raw frequency played │
│ │
│ "Spedr" 9 BYTES Current speed of the tune │
│ │
│ "Gate" 9 BYTES Key ON/OFF flags (+++/---) │
│ │
│ "Nog" 9 BYTES Tienote indicator flags │
│ │
│ "Note" 9 BYTES Current note including transp. │
│ │
│ │
│ Note that the variables offered in the header of the player will │
│ also be available though the "GlOBALS.INC" file when linking. It │
│ is recommended that you fetch the variables that way if you only │
│ plan on LINKING with the player. │
│ │
│ There are more variables in the "GLOBALS.INC" file, but since it │
│ is beyond the scope of this DOC to describe them I will leave it │
│ up to you if you want to figure them all out! ;) │
│ │
│ │
│ THE ".D00" FORMAT │
│ ───────────────── │
│ │
│ Here comes an extensive description of the ".D00" files. With it │
│ you can make support for ".D00" files in your commandline player │
│ if you're working on such a program. │
│ │
│ │
│ Offset Description │
│ ────── ─────────── │
│ │
│ 0000h-0005h Detection bytes ('JCH',26h,02h,66h) │
│ │
│ 0006h Block type (00h for music data) │
│ │
│ 0007h Player version required (Usually 04h) │
│ │
│ 0008h Timer speed for the block (Usually 46h) │
│ │
│ 0009h Number of music and SFX (Usually 01h) │
│ │
│ 000ah Soundcard (Usually 00h for AdLib) │
│ │
│ 000bh-002ah 32 bytes name of the music │
│ │
│ 002bh-004ah 32 bytes name of composer │
│ │
│ 004bh-006ah 32 bytes reserved for future expansion │
│ │
│ 006bh-006ch Pointer to "Tpoin" tables │
│ │
│ 006dh-006eh Pointer to "SeqPointer" tables │
│ │
│ 006fh-0070h Pointer to "Instrument" tables │
│ │
│ 0071h-0072h Pointer to "DataInfo" text │
│ │
│ 0073h-0074h Pointer to "Special" tables (SpFX) │
│ │
│ 0075h Endmark (FFFFh) │
│ │
│ │
│ Again, some notes about the information above may be necessary. │
│ │
│ Offset 0006h is always 00h. It was made to tell music data apart │
│ from sample data. EdLib of course always sets this to 00h. │
│ │
│ Some years ago I spread some old ".D00" music files which I made │
│ in old AdLib players (v02.00 and below). Some of this music may │
│ not sound too good in player v04.00. Check if this byte contains │
│ 04h. If it doesn't, you better avoid playing it. │
│ │
│ When using the AdLib player you should always check offset 0008h │
│ to see how many times a second the player should be called. │
│ │
│ EdLib always sets offset 0009h to 01h. You cannot make more than │
│ one piece of music at a time in the editor. │
│ │
│ Offset 000ah is always set to 00h in EdLib. If you encounter any │
│ strange ".D00" files containing any other value you better avoid │
│ playing it. │
│ │
│ Even though the ".D00" format allows 32 bytes for both the music │
│ name and the composer name, EdLib only accepts 20 characters. │
│ │
│ The pointers to various tables is really not of any interest to │
│ you, except "DataInfo" which in old songs occasionally contained │
│ additional text about the song. Tables such as "Instrument" may │
│ be useful to know in case you want to edit the ".D00" file! ;) │
│ │
│ │
│ LAST WORDS │
│ ────────── │
│ │
│ You may wonder why it takes so much time to play a pesky little │
│ AdLib tune. After all, the player is not mixing like MOD players │
│ so what the hell is going on here? Bad programming? No!! It is a │
│ sad fact but true nonetheless; When outputting a value to the FM │
│ chip like OPL2 I must wait 6 "IN" instructions after the reg has │
│ been output, and 35 (!) "IN" instructions after the value itself │
│ has been sent. If I try to decrease the number of instructions, │
│ some computers begins to play wrong; notes start falling out and │
│ play false. There ARE alternatives to using the "IN" method, one │
│ of the best is to use the "timer tick" method - but there is an │
│ even better method. │
│ │
│ One of my friends who is working on an editor for OPL3 (the four │
│ operator chip on SB Pro II and SB 16 to mention a few) found out │
│ that this chip has been optimized so much, that instead of 6 and │
│ 35 "IN's" it only requires 1 and 0 "IN's" !! I tried it on quite │
│ a lot of computers, it actually works! If the OPL3 exists it may │
│ play well in OPL2 mode with a very small CPU usage. In fact, it │
│ takes as little time as a native GUS player! :) │
│ │
│ Only one problem arises however. I have not made a detection for │
│ the OPL3 chip. I haven't even tried to, but if I find a way to │
│ do it, I may very well implement it in the next player update. I │
│ need some response on this however. If you think AdLib sucks and │
│ it doesn't make any difference, well - TUFF! │
│ │
│ If you want to contact me, look in the DOC file for EdLib itself │
│ for a snail mail or FidoNet address. │
│ │
│ This OBJ and the editor is freeware and may be used in programs │
│ that does not earn you any money, for free. If you are working │
│ on one of those commandline players for MOD, S3M, MTM (you name │
│ it), why not make support for the ".D00" format? After all, I │
│ have done most of the work for you already! :) │
│ │
│ │
│ THE BORING STUFF │
│ ──────────────── │
│ │
│ All files in the archive should be distributed in their original │
│ form - it is forbidden to modify anything. The player may not be │
│ used commercially in any way without permission from the author. │
│ │
│ The names Vibrants, the SirFace System and EdLib are trademarks │
│ of Jens-Christian Huus. Other product and company names are the │
│ trademarks of their respective owners. │
│ │
│ All warranties are disclaimed, including damage to your hardware │
│ and/or software from use of this product. In no event will I be │
│ liable to you for any damages - including any lost profits, lost │
│ savings or other incidental or consequential damages arising out │
│ of your use or inability to use the program, or any other claim │
│ by any other party. │
│ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘